<!-- saved from url=(0022)http://internet.e-mail -->
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta http-equiv="CONTENT-TYPE" content="text/html; charset=iso8859-1">
   <meta name="GENERATOR" content="Mozilla/4.75 [en]C-CCK-MCD {Nokia}  (Windows NT 5.0; U) [Netscape]">
   <meta name="AUTHOR" content="ivan wong">
   <meta name="CREATED" content="20010813;14123400">
   <meta name="CHANGED" content="20010813;18245400">
   <meta name="Author" content="Ivan Wong, Jyri Huopaniemi, Antti Rantalahti">
   <title>Overview of MIDP 2.0 Media API, Draft 7</title>
<link REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
</head>
<body>
The MIDP 2.0 Media API is a directly compatible building block of the
Mobile Media API (JSR-135) specification. The use of this building
block is intended for J2ME<sup><font size=-1>TM</font></sup> profiles
aiming to include sound support in the specification, while
maintaining upwards compatibility with the full Multimedia API. Such
specification example is MIDP 2.0 (JSR-118). The development of these
two interoperable API's enables seamless sound and multimedia content
creation across the J2ME<sup><font size=-1>TM</font></sup> range of
devices using the same API principles.

<h3>
Introduction</h3>

<blockquote>J2ME<sup><font size=-1>TM</font></sup> devices range from cell
phones with simple tone generation to PDAs and Web tablets with advanced
audio and video rendering capabilities. To accommodate diverse configurations
and multimedia processing capabilities, an API with a high level of abstraction
is needed. The goal of the MMAPI Expert Group work has been to address
this wide range of application areas, and the result of the work is a proposal
of two API sets:
<ul>
<li>
Mobile Media API (JSR 135)</li>

<li>
MIDP 2.0 Media API</li>
</ul>
The first API is intended for J2ME<sup><font size=-1>TM</font></sup> devices
with advanced sound and multimedia capabilities, including powerful mobile
phones, PDAs, and set-top boxes, for example. The latter API is a directly
compatible subset of the Multimedia API, and is intended for resource-constrained
devices such as mass-market mobile devices (running MIDP 2.0). Furthermore,
this subset API can be adopted to other J2ME<sup><font size=-1>TM</font></sup>
profiles requiring sound support. In the following, a more detailed description
of the background and requirements of the building block API is given.
</blockquote>

<h2>
<font size=+0>Background of the Media API</font></h2>
<blockquote>Some J2ME<sup><font size=-1>TM</font></sup> devices are very resource constrained.
It may not be feasible for a device to support a full range of multimedia
types, such as video on some cell phones. As a result, not all devices
are required to support the full generality of a multimedia API, such as
extensibility to support custom protocols and content types.
<p>The proposed builidng block subset API has been designed to meet the
above constraints. This proposed building block fulfills the requirements
set by the MIDP 2.0 Expert Group. These requirements include:
<ul>
<li>Low footprint audio playback
<li>Protocol and content format agnostic
<li>Supports tone generation
<li>Supports general media flow controls: start, stop, etc.
<li>Supports media-specific type controls: volume etc.
<li>Supports capability query
</ul>
This subset differs from the full Mobile Media API in the following ways:
<ul>
<li>It is audio-only.&nbsp; It excludes all Controls specific to 
video or graphics.
<li>It does not support custom protocols via custom DataSources.&nbsp; The
javax.microedition.media.protocol
package (DataSource) is excluded.
</ul>
<p>It is important to note that the building block subset used in MIDP
2.0 is a proper subset of the full Mobile Media API and is fully forward
compatible. In order to get the full Mobile Media API functionality into
MIDP 2.0 one needs to only implement the additional classes and methods
from that API.</blockquote>

<h3>
Basic Concepts</h3>

<blockquote>The proposed audio building block system constists of three
main parts.
<blockquote>
<li>
<tt>Manager</tt></li>

<li>
<tt>Player</tt></li>

<li>
<tt>Control</tt></li>
</blockquote>
The<tt> Manager</tt> is the top level controller of audio resources. Applications
use <tt>Manager</tt> to request
<tt>Players</tt> and to query properties,
supported content types and supported protocols. The manager also includes
a method to play simple tones.
<p>The<tt> Player</tt> plays the multimedia content. The application obtains
a <tt>Player</tt> by giving the locator string to <tt>Manager</tt>.
<p><tt>A Control</tt> is an interface that is used to implement all different
controls a <tt>Player</tt> might have. An application can query a <tt>Player</tt>
of controls it supports and then ask for a specific <tt>Control</tt> e.g.
<tt>VolumeControl</tt>
to control volume.</blockquote>

<blockquote>
<blockquote><img SRC="doc-files/plr-mgr-ctl.gif" ALT="DataSource, Player and Manager" height=130 width=251></blockquote>
</blockquote>

<h3>
API Details</h3>

<blockquote>The <tt>createPlayer</tt> method is the top-level entry point
to the API:
<blockquote>
<pre>Player Manager.createPlayer(String url)</pre>
</blockquote>
The <tt>url</tt> fully specifies the protocol and the content of the data:
<blockquote>
<pre>&lt;protocol&gt;:&lt;content location&gt;</pre>
</blockquote>
The <tt>Manager</tt> parses the URL, recognizes the content type and creates
a <tt>Player</tt> to handle the presentation of the data. The resulting
<tt>Player</tt>
is returned for use by the application.
Connections created by 
<code>createPlayer</code> follow the <code>Generic Connection</code>
framework rules and policies.
<p>The <tt>Player</tt> provides general methods to control the data flow
and presentation, for example:
<blockquote>
<pre>Player.realize()&nbsp;
Player.prefetch()&nbsp;
Player.start()</pre>
</blockquote>
Fine-grained control is an important feature of the API; therefore, each
<tt>Player</tt>
also provides type-specific controls with the <tt>getControls </tt>and<tt>
getControl</tt> methods:
<blockquote><tt>Control[] Player.getControls()</tt>
<br><tt>Control Player.getControl(int controlType)</tt></blockquote>
Since different types of media will yield different types of controls from
its corresponding <tt>Player</tt>, the <tt>getControls and getControl</tt>
methods can expose features that are unique to a particular media type.</blockquote>

<h3>
Tone Generation</h3>

<blockquote>Tone generation is important for games and other audio applications.&nbsp;
On very small devices, it is particularly important since that is likely
to be the only form of multimedia capabilities supported.&nbsp; In its
simplest form, tone generation reduces to a single buzzer or some simple
monophonic tone generation.&nbsp; The Manager class provides a top level
method to handle this simple form of single tone generation:
<blockquote>
<code>Manager.playTone(int note, int duration, int volume)</code>
</blockquote>
The implementation of this method can be mapped directly to the device's
hardware tone generator to provide the most responsive sound generation.
<p>In addition, the API also provides a way to create a specific type of
Player for synthesizing tone sequences:
<blockquote>
<tt>Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR)</tt>
</blockquote>
The Player created provides a special type of Control, ToneControl which
can be used for programming a tone sequence.&nbsp; This enables more sophisticated
applications written for slightly more powerful devices.</blockquote>

<h3>
Usage Scenarios</h3>

<blockquote>In this section we demonstrate how the API could be used in
four common scenarios.
<h4 STYLE="font-weight: medium">
<tt>Scenario 1: Single-Tone Generation</tt></h4>
<pre>
<blockquote>
try {
    Manager.playTone(ToneControl.C4, 5000 /* ms */, 100 /* max vol */);
} catch (MediaException e) { }
</blockquote>
</pre>

<h4 STYLE="font-weight: medium">
<tt>Scenario 2: Simple Media Playback with Looping</tt></h4>
<tt>Notice that in MIDP 2.0 the wav format is mandatory only in a case
the device supports sampled audio.</tt>

<pre>
<blockquote>
try {
    Player p = Manager.createPlayer("http://webserver/music.wav");
    p.setLoopCount(5);
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

<h4>
<tt>Scenario 3: Playing Back from Media Stored in JAR</tt></h4>
<tt>Notice that in MIDP 2.0 the wav format is mandatory only in a case
the device supports sampled audio.</tt>

<pre>
<blockquote>
try {
    InputStream is = getClass().getResourceAsStream("music.wav");
    Player p = Manager.createPlayer(is, "audio/X-wav");
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

<h4>
<tt>Scenario 4: Tone Sequence Generation</tt></h4>

<pre>
<blockquote>
/**
 * "Mary Had A Little Lamb" has "ABAC" structure.
 * Use block to repeat "A" section.
 */
byte tempo = 30; // set tempo to 120 bpm
byte d = 8;      // eighth-note

byte C4 = ToneControl.C4;;
byte D4 = (byte)(C4 + 2); // a whole step
byte E4 = (byte)(C4 + 4); // a major third
byte G4 = (byte)(C4 + 7); // a fifth
byte rest = ToneControl.SILENCE; // rest

byte[] mySequence = {
    ToneControl.VERSION, 1,   // version 1
    ToneControl.TEMPO, tempo, // set tempo
    ToneControl.BLOCK_START, 0,   // start define "A" section
    E4,d, D4,d, C4,d, E4,d,       // content of "A" section
    E4,d, E4,d, E4,d, rest,d,
    ToneControl.BLOCK_END, 0,     // end define "A" section
    ToneControl.PLAY_BLOCK, 0,    // play "A" section
    D4,d, D4,d, D4,d, rest,d,     // play "B" section
    E4,d, G4,d, G4,d, rest,d,
    ToneControl.PLAY_BLOCK, 0,    // repeat "A" section
    D4,d, D4,d, E4,d, D4,d, C4,d  // play "C" section
};

try{
    Player p = Manager.createPlayer(Manager.TONE_DEVICE_LOCATOR);
    p.realize();
    ToneControl c = (ToneControl)p.getControl("ToneControl");
    c.setSequence(mySequence);
    p.start();
} catch (IOException ioe) {
} catch (MediaException me) { }
</blockquote>
</pre>

</blockquote>

@since MIDP 2.0

</body>
</html>
